home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem7.asc < prev    next >
Text File  |  1987-10-10  |  17KB  |  377 lines
  1.                         *PROFESSIONAL GEM*
  2.                            By Tim Oren
  3.                    Column #7 - Menu Structures
  4.  
  5.     HAPPY NEW YEAR!  This is article number seven in the ST
  6. PRO GEM series, and the first for 1986.  In this installment,
  7. I will be discussing GEM menu structures and how to use them
  8. in your application.  There is  also a short Feedback
  9. response section.  You will find the download file containing
  10. the code for this column in the file GEMCL7.C in DL3 of the
  11. ATARI16 SIG (PCS-58).
  12.  
  13.     MENU BASICS.  In ST GEM, the menu consists of a bar
  14. across the top of the screen which displays several sub-menu
  15. titles.  Touching one of the titles causes it to highlight,
  16. and an associated "drop-down" to be drawn  directly below on
  17. the screen.  This drop-down may be dismissed by moving  to
  18. another title, or by clicking the mouse off of the drop-down.
  19.  
  20.  
  21.     To make a selection, the mouse is moved over the
  22. drop-down.  Each  valid selection is highlighted when the
  23. mouse touches it.  Clicking the mouse  while over one of
  24. these selections picks that item.  GEM then undraws the
  25. drop-down, and sends a message to your application giving the
  26. object number  of the title bar entry, and the object number
  27. of the drop-down item which  were selected by the user.  The
  28. selected title entry is left highlighted  while your code
  29. processes the request.
  30.  
  31.     MENU STRUCTURES.  The data structure which defines a GEM
  32. menu is (surprise!) an object tree, just like the dialogs and
  33. panels which we have discussed before.  However, the
  34. operations of the GEM menu manager are quite different from
  35. those of the form manager, so the internal design of the menu
  36. tree has some curious constraints.
  37.  
  38.     The best way to understand these constraints is to look
  39. at an  example.  The first item in the download is the object
  40. structure (only) of the menu tree from the GEM Doodle/Demo
  41. sample application.
  42.  
  43.     The ROOT of a menu tree is sized to fit the entire
  44. screen.  To satisfy the visual hierarchy principle (see
  45. article #5), the screen is divided into two parts: THE BAR,
  46. containing the menu titles, and THE SCREEN, while contains
  47. the drop-downs when they are drawn.  Each of these areas is
  48. defined by an object of the same name, which are the only two
  49. objects linked directly below the ROOT of a menu tree.  You
  50. will notice an important implication of this structure:  The
  51. menu titles and their associated drop-downs are stored in
  52. entirely different subtrees of the menu!
  53.  
  54.     While examining THE BAR in the example listing, you may
  55. notice that its OB_HEIGHT is very large (513).  In
  56. hexadecimal this is 0x0201.  This defines a height for THE
  57. BAR of one character plus two pixels used for spacing.  THE
  58. BAR and its subtree are the only objects which are drawn on
  59. the screen in the menu's quiescent state.
  60.  
  61.     The only offspring object of THE BAR is THE ACTIVE.  This
  62. object defines the part of THE BAR which is covered by menu
  63. titles.  The screen rectangle belonging to THE ACTIVE is used
  64. by the GEM screen manager when it  waits for the mouse to
  65. enter an active menu title.  Notice that THE ACTIVE and its
  66. offspring also have OB_HEIGHTs with pixel residues.
  67.  
  68.     The actual menu titles are linked left to right in order
  69. below THE ACTIVE.  Their OB_Xs and OB_WIDTHs are arranged so
  70. that they  completely cover THE ACTIVE.  Normally, the title
  71. objects are typed  G_TITLE, a special type which assures that
  72. the title bar margins are correctly drawn.
  73.  
  74.     THE SCREEN is the parent object of the drop-down boxes
  75. themselves. They are linked left to right in an order
  76. identical with their titles, so  that the menu manager can
  77. make the correct correspondence at run-time.  The OB_X of
  78. each drop-down is set so that it is positioned below its
  79. title on the screen.
  80.  
  81.     Notice that it is safe to overlap the drop-downs within a
  82. menu,  since only one of them will be displayed at any time.
  83. There is one constraint on the boxes however:  They must be
  84. no greater than a quarter screen in total size.  This is the
  85. size of the off-screen blit buffer which is used by GEM to
  86. store the screen contents when the drop-down is drawn.  If
  87. you exceed this size, not all the screen under the drop-down
  88. will be restored, or the ST may crash!
  89.  
  90.     The entries within a drop-down are usually G_STRINGs,
  91. which are optimized for drawing speed.  The rectangles of
  92. these entries must  completely cover the drop-down, or the
  93. entire drop-down will be inverted  when the mouse touches an
  94. uncovered area!  Techniques for using objects  other than
  95. G_STRINGs are discussed later in this column.
  96.  
  97.     The first title and its corresponding drop-down are
  98. special.  The title name, by custom, is set to DESK.  The
  99. drop-down must contain exactly  eight G_STRING objects.  The
  100. first (again by custom) is the INFO entry,  which usually
  101. leads to a dialog displaying author and copyright information
  102. for your application.  The next is a separator string of
  103. dashes with the DISABLED flag set.  The following six objects
  104. are dummy strings which GEM fills in with the names of desk
  105. accessories when your menu is loaded.
  106.  
  107.     The purpose of this description of menu trees is to give
  108. you an understanding of what lies "behind the scenes" in the
  109. next section, which describes the run-time menu library
  110. calls.  In practice, the Resource Construction Set provides
  111. "blank menus" which include all of the required elements, and
  112. it also enforces the constraints on internal structure.  You
  113. only need to worry about these if you modify the menu tree
  114. "on-the-fly".
  115.  
  116.     USING THE MENU.  Once you have loaded the application's
  117. resource, you can ask the AES to install your menu.  You must
  118. first get the address of the menu tree within the resource
  119. using:
  120.  
  121.     rsrc_gaddr(R_TREE, MENUTREE, &ad_menu);
  122.  
  123.  assuming that MENUTREE is the name you gave the menu in the
  124. RCS, and that ad_menu is a LONG which will receive the
  125. address.  Then you call the AES to establish the menu:
  126.  
  127.     menu_bar(ad_menu, TRUE);
  128.  
  129.  At this point, the AES draws your menu bar on the screen and
  130. animates it when the user moves the mouse into the title
  131. area.
  132.  
  133.     The AES indicates that the user has made a menu selection
  134. by sending your application a message.  The message type is
  135. MN_SELECTED,  which will be stored in msg[0], the first
  136. location in the message  returned by evnt_multi().
  137.  
  138.     The AES also stores the object number of the selected
  139. menu's  title in msg[3], and the object number of the
  140. selected menu item in msg[4].  Generally, your application
  141. will process menu messages with nested C switch statements.
  142. The outer switch will have one case for each menu title, and
  143. the inner switch statements will have a case for each entry
  144. within the selected menu.  (This implies that you must give a
  145. name to each title and to each menu entry when you create the
  146. menu in the RCS.)
  147.  
  148.     After the user has made a menu selection, the AES leaves
  149. the title of the chosen menu in reverse video to indicate
  150. that your application is busy processing the message.  When
  151. you done with whatever action is indicated, you need to
  152. return the title to a normal state. This is done with
  153.  
  154.     menu_tnormal(ad_menu, msg[3], TRUE);
  155.  
  156.  (Remember that msg[3] is the title's object number.)
  157.  
  158.     When your application is ready to terminate, it should
  159. delete its menu bar.  Do this with the call:
  160. menu_bar(ad_menu, FALSE);
  161.  
  162.     GETTING FANCY.  The techniques above represent the bare
  163. minimum to handle menus.  In most cases, however, you will
  164. want your menus to be more "intelligent" in displaying the
  165. user's options.  For instance, you can prevent many user
  166. errors by disabling inappropriate choices, or you can save
  167. space on drop-downs by showing only one line for a toggle and
  168. altering its text or placing and removing a check mark when
  169. the state is changed.  This section discusses these and other
  170. advanced techniques.
  171.  
  172.     It is a truism of user interface design that the best way
  173. to deal with an error is not to let it happen in the first
  174. place.  It  many cases, you can apply this principle to GEM
  175. menus by disabling  choices which should not be used.  If
  176. your application uses a "selection  precedes action" type of
  177. interface, the type of object selected may  give the
  178. information needed to do